.TH std::time_put::put,std::time_put::do_put 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::time_put::put,std::time_put::do_put \- std::time_put::put,std::time_put::do_put

.SH Synopsis
   Defined in header <locale>
   public:

   iter_type put( iter_type out, std::ios_base& str,                \fB(1)\fP
                  char_type fill, const std::tm* t,

                  const CharT* fmtbeg, const CharT* fmtend ) const;
   public:

   iter_type put( iter_type out, std::ios_base& str,                \fB(2)\fP
                  char_type fill, const std::tm* t,

                  char format, char modifier = 0 ) const;
   protected:

   virtual iter_type do_put( iter_type out, std::ios_base& str,     \fB(3)\fP
                             char_type fill, const std::tm* t,

                             char format, char modifier ) const;

   Converts the calendar date and time stored in the std::tm object pointed to by t
   into a character string, according to the format string [fmtbeg, fmtend). The format
   string is the same as used by std::strftime, but each format specifier is processed
   by an individual call to do_put(), which can be customized by extending this facet.

   1) Steps through the character sequence [fmtbeg, fmtend), examining the characters.
   Every character that is not a part of a format sequence is written to the output
   iterator out immediately. To identify format sequences, this function narrows the
   next character c in [fmtbeg, fmtend) as if by
   std::ctype<char_type>(str.getloc()).narrow(c, 0) and if it equals '%', the next one
   or two characters are compared to the list of format sequences recognized by
   std::strftime plus any additional implementation-defined formats supported by this
   locale. For each valid format sequence, a call to do_put(out, str, fill, t, format,
   modifier) is made, where format is the format sequence character, and modifier is
   the optional format sequence modifier ('E' or 'O'). A value of '\\0' is used if the
   modifier is absent.
   2) Calls the do_put member function of the most derived class.
   3) Converts the calendar date and time stored in the std::tm object pointed to by t
   into a character string, according to the format conversion sequence formed by
   concatenating '%', the value of modifier if not '\\0', and the value of format. The
   format is interpreted the same way as the function std::strftime, except that the
   formats that are described as locale-dependent are defined by this locale, and
   additional format specifiers may be supported (the fill argument is provided for
   these implementation-defined format specifiers to use). The string is written to the
   output iterator out.

.SH Parameters

   out      - output iterator where the result of the conversion is written
   str      - a stream object that this function uses to obtain locale facets when
              needed, e.g. std::ctype to narrow characters
   t        - pointer to the std::tm object from which the date/time values are
              obtained
   fmtbeg   - pointer to the first character of a sequence of char_type characters
              specifying the conversion format
   fmtend   - pointer one past the last character of a sequence of char_type characters
              specifying the conversion format
   fill     - fill character (usually space)
   format   - the character that names a conversion specifier
   modifier - the optional modifier that may appear between % and the conversion
              specifier

   Format string

   The format string consists of zero or more conversion specifiers and ordinary
   characters (except %). All ordinary characters, including the terminating null
   character, are copied to the output string without modification. Each conversion
   specification begins with % character, optionally followed by E or O modifier
   (ignored if unsupported by the locale), followed by the character that determines
   the behavior of the specifier. The following format specifiers are available:

   Conversion                       Explanation                          Used fields
   specifier
       %      writes literal %. The full conversion specification
              must be %%.
       n      writes newline character
    \fI(C++11)\fP
       t      writes horizontal tab character
    \fI(C++11)\fP
                                           Year
       Y      writes year as a decimal number, e.g. 2017              tm_year
       EY     writes year in the alternative representation, e.g.平
    \fI(C++11)\fP   成23年 (year Heisei 23) instead of 2011年 (year 2011)   tm_year
              in ja_JP locale
       y      writes last 2 digits of year as a decimal number (range tm_year
              [00,99])
       Oy     writes last 2 digits of year using the alternative      tm_year
    \fI(C++11)\fP   numeric system, e.g. 十一 instead of 11 in ja_JP locale
       Ey     writes year as offset from locale's alternative         tm_year
    \fI(C++11)\fP   calendar period %EC (locale-dependent)
       C      writes first 2 digits of year as a decimal number       tm_year
    \fI(C++11)\fP   (range [00,99])
       EC     writes name of the base year (period) in the locale's
    \fI(C++11)\fP   alternative representation, e.g. 平成 (Heisei era) in   tm_year
              ja_JP
              writes ISO 8601 week-based year, i.e. the year that
              contains the specified week.

       G      In ISO 8601 weeks begin with Monday and the first week  tm_year, tm_wday,
    \fI(C++11)\fP   of the year must satisfy the following requirements:    tm_yday

                * Includes January 4
                * Includes first Thursday of the year
              writes last 2 digits of ISO 8601 week-based year, i.e.
              the year that contains the specified week (range
              [00,99]).
       g                                                              tm_year, tm_wday,
    \fI(C++11)\fP   In ISO 8601 weeks begin with Monday and the first week  tm_yday
              of the year must satisfy the following requirements:

                * Includes January 4
                * Includes first Thursday of the year
                                          Month
       b      writes abbreviated month name, e.g. Oct (locale         tm_mon
              dependent)
       h      synonym of b                                            tm_mon
    \fI(C++11)\fP
       B      writes full month name, e.g. October (locale dependent) tm_mon
       m      writes month as a decimal number (range [01,12])        tm_mon
       Om     writes month using the alternative numeric system, e.g. tm_mon
    \fI(C++11)\fP   十二 instead of 12 in ja_JP locale
                                           Week
       U      writes week of the year as a decimal number (Sunday is  tm_year, tm_wday,
              the first day of the week) (range [00,53])              tm_yday
       OU     writes week of the year, as by %U, using the            tm_year, tm_wday,
    \fI(C++11)\fP   alternative numeric system, e.g. 五十二 instead of 52   tm_yday
              in ja_JP locale
       W      writes week of the year as a decimal number (Monday is  tm_year, tm_wday,
              the first day of the week) (range [00,53])              tm_yday
       OW     writes week of the year, as by %W, using the            tm_year, tm_wday,
    \fI(C++11)\fP   alternative numeric system, e.g. 五十二 instead of 52   tm_yday
              in ja_JP locale
              writes ISO 8601 week of the year (range [01,53]).

       V      In ISO 8601 weeks begin with Monday and the first week  tm_year, tm_wday,
    \fI(C++11)\fP   of the year must satisfy the following requirements:    tm_yday

                * Includes January 4
                * Includes first Thursday of the year
       OV     writes week of the year, as by %V, using the            tm_year, tm_wday,
    \fI(C++11)\fP   alternative numeric system, e.g. 五十二 instead of 52   tm_yday
              in ja_JP locale
                                  Day of the year/month
       j      writes day of the year as a decimal number (range       tm_yday
              [001,366])
       d      writes day of the month as a decimal number (range      tm_mday
              [01,31])
              writes zero-based day of the month using the
       Od     alternative numeric system, e.g. 二十七 instead of 27
    \fI(C++11)\fP   in ja_JP locale                                         tm_mday

              Single character is preceded by a space.
              writes day of the month as a decimal number (range
       e      [1,31]).                                                tm_mday
    \fI(C++11)\fP
              Single digit is preceded by a space.
              writes one-based day of the month using the alternative
       Oe     numeric system, e.g. 二十七 instead of 27 in ja_JP
    \fI(C++11)\fP   locale                                                  tm_mday

              Single character is preceded by a space.
                                     Day of the week
       a      writes abbreviated weekday name, e.g. Fri (locale       tm_wday
              dependent)
       A      writes full weekday name, e.g. Friday (locale           tm_wday
              dependent)
       w      writes weekday as a decimal number, where Sunday is 0   tm_wday
              (range [0-6])
       Ow     writes weekday, where Sunday is 0, using the
    \fI(C++11)\fP   alternative numeric system, e.g. 二 instead of 2 in     tm_wday
              ja_JP locale
       u      writes weekday as a decimal number, where Monday is 1   tm_wday
    \fI(C++11)\fP   (ISO 8601 format) (range [1-7])
       Ou     writes weekday, where Monday is 1, using the
    \fI(C++11)\fP   alternative numeric system, e.g. 二 instead of 2 in     tm_wday
              ja_JP locale
                                   Hour, minute, second
       H      writes hour as a decimal number, 24 hour clock (range   tm_hour
              [00-23])
       OH     writes hour from 24-hour clock using the alternative    tm_hour
    \fI(C++11)\fP   numeric system, e.g. 十八 instead of 18 in ja_JP locale
       I      writes hour as a decimal number, 12 hour clock (range   tm_hour
              [01,12])
       OI     writes hour from 12-hour clock using the alternative    tm_hour
    \fI(C++11)\fP   numeric system, e.g. 六 instead of 06 in ja_JP locale
       M      writes minute as a decimal number (range [00,59])       tm_min
       OM     writes minute using the alternative numeric system,     tm_min
    \fI(C++11)\fP   e.g. 二十五 instead of 25 in ja_JP locale
       S      writes second as a decimal number (range [00,60])       tm_sec
       OS     writes second using the alternative numeric system,     tm_sec
    \fI(C++11)\fP   e.g. 二十四 instead of 24 in ja_JP locale
.SH Other
       c      writes standard date and time string, e.g. Sun Oct 17   all
              04:41:13 2010 (locale dependent)
       Ec     writes alternative date and time string, e.g. using 平
    \fI(C++11)\fP   成23年 (year Heisei 23) instead of 2011年 (year 2011)   all
              in ja_JP locale
       x      writes localized date representation (locale dependent) all
       Ex     writes alternative date representation, e.g. using 平
    \fI(C++11)\fP   成23年 (year Heisei 23) instead of 2011年 (year 2011)   all
              in ja_JP locale
       X      writes localized time representation, e.g. 18:40:20 or  all
              6:40:20 PM (locale dependent)
       EX     writes alternative time representation (locale          all
    \fI(C++11)\fP   dependent)
       D      equivalent to "%m/%d/%y"                                tm_mon, tm_mday,
    \fI(C++11)\fP                                                           tm_year
       F      equivalent to "%Y-%m-%d" (the ISO 8601 date format)     tm_mon, tm_mday,
    \fI(C++11)\fP                                                           tm_year
       r      writes localized 12-hour clock time (locale dependent)  tm_hour, tm_min,
    \fI(C++11)\fP                                                           tm_sec
       R      equivalent to "%H:%M"                                   tm_hour, tm_min
    \fI(C++11)\fP
       T      equivalent to "%H:%M:%S" (the ISO 8601 time format)     tm_hour, tm_min,
    \fI(C++11)\fP                                                           tm_sec
       p      writes localized a.m. or p.m. (locale dependent)        tm_hour
       z      writes offset from UTC in the ISO 8601 format (e.g.
    \fI(C++11)\fP   -0430), or no characters if the time zone information   tm_isdst
              is not available
              writes locale-dependent time zone name or abbreviation,
       Z      or no characters if the time zone information is not    tm_isdst
              available

.SH Return value

   Iterator pointing one past the last character that was produced.

.SH Notes

   No error handling is provided.

   The fill character is provided for those implementation-defined format specifiers
   and for the user-defined overrides of do_put() that use padding and filling logic.
   Such implementations typically make use of the formatting flags from str.

.SH Example


// Run this code

 #include <iostream>
 #include <sstream>
 #include <iomanip>
 #include <ctime>

 void try_time_put(const std::tm* t, const std::string& fmt)
 {
     std::cout.imbue(std::locale());
     std::cout << "In the locale '" << std::cout.getloc().name() << "' : '";

     std::use_facet<std::time_put<char>>(std::cout.getloc()).put(
         {std::cout}, std::cout, ' ', t, &fmt[0], &fmt[0] + fmt.size());

     std::cout << "'\\n";
 }

 int main()
 {
     std::time_t t = std::time(NULL);
     std::tm tm = *std::localtime(&t);

     std::string fmt = "%c";
     std::cout << "Using the format string '" << fmt
               << "' to format the time: " << std::ctime(&t) << '\\n';

     std::locale::global(std::locale("de_DE.utf8"));
     try_time_put(&tm, fmt);

     std::locale::global(std::locale("el_GR.utf8"));
     try_time_put(&tm, fmt);

     std::locale::global(std::locale("ja_JP.utf8"));
     try_time_put(&tm, fmt);
 }

.SH Possible output:

 Using the format string '%c' to format the time: Mon Feb 11 22:58:50 2013

 In the locale 'de_DE.utf8' : 'Mo 11 Feb 2013 23:02:38 EST'
 In the locale 'el_GR.utf8' : 'Δευ 11 Φεβ 2013 11:02:38 μμ EST'
 In the locale 'ja_JP.utf8' : '2013年02月11日 23時02分38秒'

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to              Behavior as published              Correct behavior
   LWG 164 C++98      the purpose of the parameter fill was not clear made clear

.SH See also

   put_time          formats and outputs a date/time value according to the specified
   \fI(C++11)\fP           format
                     \fI(function template)\fP
                     extracts date/time components from input stream, according to the
   do_get            specified format
   \fB[virtual]\fP \fI(C++11)\fP \fI\fI(virtual protected member function\fP of\fP
                     std::time_get<CharT,InputIt>)
